﻿@page "/docs/specifications/autocomplete"

<Seo Canonical="/docs/specifications/autocomplete" Title="Blazorise Specifications: Autocomplete" Description="Learn about Blazorise Autocomplete component and how it works and behaves under the certain scenarios, according to the defined parameters." />

<DocsPageTitle Path="Specifications/Autocomplete">
    Blazorise Specifications: Autocomplete
</DocsPageTitle>

<DocsPageLead>
    Learn how the Autocomplete works and behaves under the certain scenarios, according to the defined parameters
</DocsPageLead>

<DocsPageSubtitle>
    AutoSelectFirstItem
</DocsPageSubtitle>

<DocsPageParagraph>
    When active, the Autocomplete will attempt to select the first option upon initializing. This will trigger the change events.
    This is specially usefull when you've specified <Code>ReadData</Code>.
</DocsPageParagraph>

<DocsPageParagraph>
    This option is only available when the Autocomplete is in <Code>AutocompleteSelectionMode.Default</Code>.
</DocsPageParagraph>

<DocsPageSubtitle>
    AutoPreSelect
</DocsPageSubtitle>

<DocsPageParagraph>
    When disabled, the first option in the <Code>Autocomplete</Code> suggestion's box will no longer be "PreSelected".
</DocsPageParagraph>

<DocsPageParagraph>
    This is specially useful for a corner case.
    If you would like your User to input a Free typed value (by using <Code>FreeTyping</Code>) you might want to consider disabling this option.
    In this manner, your User may Enter a similar value to the one's suggested by the <Code>Autocomplete</Code>, however this will make it so the confirmation Key does not Select the "PreSelected" option.
</DocsPageParagraph>

<DocsPageParagraph>
    Please note the following simple example, where we would like a user to be able to commit a value of 10000 as their Employee Id, even tough there are suggestions based on that same number.
</DocsPageParagraph>

<Table>
    <TableHeader>
        <TableRowHeader>AutoPreSelect</TableRowHeader>
        <TableRowHeader>AutoPreSelect Disabled</TableRowHeader>
    </TableHeader>
    <TableBody>
        <TableRowCell>
            Pressing the commit key will commit the first option.
            <Image Source="@($"img/specifications/autocomplete/AutoPreSelect.gif")" Text="AutoPreSelect image" />
        </TableRowCell>
        <TableRowCell>
            Pressing the commit key will not commit the first option, as it is not PreSelected.
            <Image Source="@($"img/specifications/autocomplete/AutoPreSelectFalse.gif")" Text="AutoPreSelect Disabled image" />
        </TableRowCell>
    </TableBody>
</Table>

<DocsPageSubtitle>
    CloseOnSelection
</DocsPageSubtitle>

<DocsPageParagraph>
    By default <Code>Autocomplete</Code> will close the suggestion's box upon the value being confirmed.
    However you might want it to remain open, this is specially usefull if you have the <Code>Autocomplete</Code> set to <Code>AutocompleteSelectionMode.Multiple</Code> or <Code>AutocompleteSelectionMode.Checkbox</Code>
    Here's an example:
</DocsPageParagraph>

<DocsPageParagraph>
    <Image Source="@($"img/specifications/autocomplete/CloseOnSelection.gif")" Text="CloseOnSelection image" />
</DocsPageParagraph>

<DocsPageSubtitle>
    MinLength
</DocsPageSubtitle>

<DocsPageParagraph>
    This <Code>Parameter</Code> is quite self descriptive, it'll start displaying eligibile options from a defined minimum length, it defaults to the value of 1.
</DocsPageParagraph>

<DocsPageParagraph>
    A recurring question, is how to display every <Code>Autocomplete</Code> option upon focus.
    Setting this <Code>Parameter</Code>  to the value of 0 is how you do it.
</DocsPageParagraph>

<DocsPageSubtitle>
    Changed Triggers
</DocsPageSubtitle>

<DocsPageParagraph>
    Sometimes it's important to know when to expect a <Code>Parameter</Code> Changed <Code>EventCallback</Code> will trigger.
    The following table displays some common combinations which we find important for you to know.
</DocsPageParagraph>

<Table>
    <TableHeader>
        <TableRow>
            <TableHeaderCell Style="width:20%;">SelectedValueChanged</TableHeaderCell>
            <TableHeaderCell Style="width:30%;">FreeTyping</TableHeaderCell>
            <TableHeaderCell Style="width:30%;">No FreeTyping</TableHeaderCell>
            <TableHeaderCell Style="width:20%;">AutoSelectFirstItem</TableHeaderCell>
        </TableRow>
    </TableHeader>
    <TableBody>
        <TableRow>
            <TableRowHeader>Component Initialized</TableRowHeader>
            <TableRowCell></TableRowCell>
            <TableRowCell></TableRowCell>
            <TableRowCell>
                Triggers If <Code>Multiple="false"</Code>
            </TableRowCell>
        </TableRow>

        <TableRow>
            <TableRowHeader>User Input</TableRowHeader>
            <TableRowCell>
                <UnorderedList>
                    <UnorderedListItem>
                        If SelectedValue has been found.
                    </UnorderedListItem>
                    <UnorderedListItem>
                        If SelectedValue has not been found. (If the current SelectedValue is not already default (null))
                    </UnorderedListItem>
                </UnorderedList>
            </TableRowCell>
            <TableRowCell>
                <UnorderedList>
                    <UnorderedListItem>
                        If SelectedValue has been found.
                    </UnorderedListItem>
                    <UnorderedListItem>
                        If SelectedValue has not been found. (If the current SelectedValue is not already default (null))
                    </UnorderedListItem>
                </UnorderedList>
            </TableRowCell>
            <TableRowCell></TableRowCell>
        </TableRow>
    </TableBody>
</Table>

<Table>
    <TableHeader>
        <TableRow>
            <TableHeaderCell Style="width:20%;">SelectedTextChanged</TableHeaderCell>
            <TableHeaderCell Style="width:30%;">FreeTyping</TableHeaderCell>
            <TableHeaderCell Style="width:30%;">No FreeTyping</TableHeaderCell>
            <TableHeaderCell Style="width:20%;">AutoSelectFirstItem</TableHeaderCell>
        </TableRow>
    </TableHeader>
    <TableBody>
        <TableRow>
            <TableRowHeader>Component Initialized</TableRowHeader>
            <TableRowCell></TableRowCell>
            <TableRowCell></TableRowCell>
            <TableRowCell>
                Triggers If <Code>Multiple="false"</Code>
            </TableRowCell>
        </TableRow>

        <TableRow>
            <TableRowHeader>User Input</TableRowHeader>
            <TableRowCell>
                Triggers Always
            </TableRowCell>
            <TableRowCell>
                <UnorderedList>
                    <UnorderedListItem>
                        If SelectedText has been found.
                    </UnorderedListItem>
                    <UnorderedListItem>
                        If SelectedText has not been found. (If the current SelectedText is not already default (null))
                    </UnorderedListItem>
                </UnorderedList>
            </TableRowCell>
            <TableRowCell></TableRowCell>
        </TableRow>
    </TableBody>
</Table>
